Inside Macintosh: Telephony /

Chapter 6 - Telephone Tools / Telephone Tools Reference

Constants

Call Appearance Messages

This section describes the messages that a telephone tool can send to the Telephone Manager's call appearance master message handler. These messages are relayed to any applications that have installed a call appearance message handler. Your tool passes the message type and any necessary additional information in the fields of a parameter block, the type of which depends on the message being passed.

Note

See "Call Appearance Messages," beginning on page 5-14 for a description of how the call appearance message type and additional information are passed to applications.

enum {
   telCAAlertingMsg        = 0x00000001,
   telCAOfferMsg           = 0x00000002,
   telCAProgressMsg        = 0x00000004,
   telCAOutgoingMsg        = 0x00000008,
   telCADisconnectMsg      = 0x00000010,
   telCAActiveMsg          = 0x00000020,
   telCAConferenceMsg      = 0x00000040,
   telCATransferMsg        = 0x00000080,
   telCAHoldMsg            = 0x00000100,
   telCADigitsMsg          = 0x00000200,
   telCACallParkMsg        = 0x00000400,
   telCACallbackMsg        = 0x00000800,
   telCARejectMsg          = 0x00001000,
   telCADeflectMsg         = 0x00002000,
   telCAForwardMsg         = 0x00004000,
   telCAConferenceSplitMsg = 0x00008000,
   telCAConferenceDropMsg  = 0x00010000,
   telCAQueuedMsg          = 0x00020000,
   telCAInUseMsg           = 0x00040000,
   telCACallPickupMsg      = 0x00080000,
   telCAPagingMsg          = 0x00100000,
   telCAIntercomMsg        = 0x00200000,
   telCAModemToneMsg       = 0x00400000,
   telCAFaxToneMsg         = 0x00800000,
   telCAIdleMsg            = 0x01000000,
   telCASuccessiveAlertMsg = 0x02000000,
   telCAUserUserInfoMsg    = 0x04000000,
   telCAHandOffMsg         = 0x08000000,
   telCAVoiceDetectedMsg   = 0x10000000,
   telCASilenceDetectedMsg = 0x20000000,
   telCADigitsImmMsg       = 0x40000000,
   telCAOtherMsg           = 0x80000000
};

Constant descriptions

telCAAlertingMsg

Your tool sends this message when an incoming call is alerting (that is, ringing) at a telephone terminal. You pass information to the Telephone Manager using a call appearance incoming or outgoing message parameter block (page 6-68). The mtype field is not used and should be set to 0. The value field is a constant that indicates the alerting pattern of the incoming call. The possible values for this constant are described in "Alerting Patterns" on page 2-15.

telCAOfferMsg

Your tool sends this message when an incoming call is being offered to the local terminal. You pass information to the Telephone Manager using a call appearance incoming or outgoing message parameter block (page 6-68). The mtype, value, and msgInfo fields are not used and should be set to 0.

telCAProgressMsg

Your tool sends this message when there is a change in the status of an outgoing call appearance. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mType parameter may contain a duration value, expressed in milliseconds. If the duration value is unknown, if it is not meaningful with a given call progress signal, or if the progressHasDuration bit is not set, mType should contain 0. The value parameter is a constant that indicates the current state of the outgoing call appearance. See "Call Progress Signals" on page 5-30 for a description of the constants that can be passed in this parameter. If the value parameter contains the constant telCAPUpdate or telCAPRouted, you should update the rmtDN, rmtPartyName, and rmtSubaddress fields in the call appearance generic message parameter block.

telCAOutgoingMsg

Your tool sends this message when an outgoing call appearance has been initiated. You pass information to the Telephone Manager using a call appearance incoming or outgoing message parameter block (page 6-68). The mtype parameter is not used and should be set to 0. The value parameter is a constant that indicates whether the call was initiated manually or programmatically. The possible values for this constant are described in "Outgoing Origination States" on page 5-40.

telCADisconnectMsg

Your tool sends this message when a call has been disconnected. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is a constant that indicates whether the local party or the remote party terminated the connection. The constants are described in "Disconnect Location Messages" (page 5-36). The value field is a constant that indicates the reason for the disconnect. The possible values for this constant are described in "Disconnect Types" on page 5-36. The rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAActiveMsg

Your tool sends this message when a call appearance has been successfully connected to the destination and conversation or data is free to flow over the connection. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype, value, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAConferenceMsg

Your tool sends this message when (1) an application calls the TELConferencePrep function to establish a connection with a party to be added to a conference; (2) an application calls the TELConferenceEstablish function to add a new party to a conference; or (3) the user manually sets up a conference. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should be set to 0. The value field contains a constant that indicates the success or failure of an attempt to prepare for and establish a conference. See "Conference Activity States" on page 5-34 for the constants you can pass in this parameter.

telCATransferMsg

Your tool sends this message when (1) an application calls the TELTransferPrep, TELTransferEstablish, or TELTransferBlind function to transfer a call; (2) a user manually transfers a call; or (3) a call originated by your tool is transferred by the remote end. You pass information to the Telephone Manager using a call appearance transfer message parameter block (page 6-66). The mtype field is unused and should be set to 0. The value field contains a constant that indicates the outcome of the transfer activity. See "Transfer Constants" on page 5-42 for the constants you can pass in this field. If the value field contains telTransferEst or telTransferFailed, the rmtDN, rmtName, and rmtSubaddress fields should specify the directory number, user, and subaddress to which the call is to be or has been transferred. Otherwise, those fields should be set to 0.

telCAHoldMsg

Your tool sends this message when (1) an application calls the TELHold or TELRetrieve function to hold or retrieve a call appearance, or (2) a user manually puts a call on hold or retrieves a held call. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should be set to 0. The value field contains a constant that indicates the outcome of the hold activity. See "Hold States" on page 5-38 for the constants you can pass in this field. The rmtDN, rmtName, rmtSubaddress, and dialType fields are unused and should be set to 0.

telCADigitsMsg

Your tool sends this message when a key is pressed at a remote directory number. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is a constant that indicates whether or not the key press generated an audible tone. These constants are described in "Audible Digit States" on page 5-32. The value field is the ASCII character for the keypad digit (0-9, #, *) pressed by the remote party. Note that your tool should send both telCADigitsMsg and telCADigitsImmMsg messages for each remote keypress. The rmtDN, rmtName, rmtSubaddress, and dialType fields are unused and should be set to 0.

telCACallParkMsg

Your tool sends this message when (1) an application calls the TELParkCall or TELRetrieveParkedCall function to park a call or retrieve a parked call, or (2) a user manually parks or retrieves a call. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and is set to 0. The value field contains a constant that indicates the outcome of call parking activity. The constants are listed in "Call Parking States" (page 5-41). The rmtDN, rmtName, rmtSubaddress, and dialType fields specify the remote directory number at which the call is available for retrieving. If either your tool or the telephone network switch doesn't support parking calls against directory numbers, you should set those fields to 0.

telCACallbackMsg

Your tool sends this message when there is callback activity for a call appearance. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field contains a valid callback reference, if there is one; otherwise, mtype should contain 0. The value field contains a constant that indicates the type of callback activity. The constants are described in "Callback Activity Types" (page 5-33). The rmtDN, rmtName, rmtSubaddress, and dialType fields specify the remote directory number associated with the callback. If the remote directory number is unavailable or not supported by your tool, you should set those fields to 0.

telCARejectMsg

Your tool sends this message when (1) an application calls the TELRejectCall function to reject a call; (2) a user manually rejects a call; or (3) a call originated by an application is rejected by the remote end. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and is set to 0. The value field contains a constant that indicates the type or outcome of call rejection activity. The constants are described in "Call Rejection States" (page 5-42). The rmtDN, rmtName, rmtSubaddress, and dialType fields are unused and should be set to 0.

telCADeflectMsg

Your tool sends this message when (1) an application calls the TELDeflectCall function to deflect an incoming call; (2) a user manually deflects an incoming call; (3) call forwarding is in effect for the local directory number and an incoming call is automatically deflected as a result; or (4) the remote party deflects an outgoing call to a new directory number. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should be set to 0. The value field contains a constant that indicates the type and outcome of call-deflect activity. The constants are described in "Call Deflect Messages" (page 5-35). The rmtDN, rmtName, rmtSubaddress, and dialType fields specify the remote directory number to which the call is being deflected.

telCAForwardMsg

Your tool sends this message when a call that you originated is forwarded by the remote party to another directory number. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should be set to 0. The value field contains a constant that indicates type of call forwarding in effect at the remote number. The constants are described in "Call Forward Types and States" (page 5-28). The rmtDN, rmtName, rmtSubaddress, and dialType fields specify the remote directory number to which the call is being forwarded.

telCAConferenceSplitMsg

Your tool sends this message when an application calls the TELConferenceSplit function to split a conference call. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should be set to 0. The value field contains a constant that indicates the success or failure of the attempt to split a conference call. See "Conference Split States" on page 5-35 for the constants you can pass in this parameter.

telCAConferenceDropMsg

Your tool sends this message when an application calls the TELDrop function to drop a call appearance from a conference. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should be set to 0. The value field contains a constant that indicates the success or failure of the attempt to drop a conference call. See "Conference Drop States" on page 5-34 for the constants you can pass in this parameter.

telCAQueuedMsg

Your tool sends this message when an incoming call is queued to be answered. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype, value, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAInUseMsg

Your tool sends this message when an incoming call to a multiple-access directory number (MADN) is in use, but at another terminal. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0. The value field is a constant that provides additional information about the call appearance. The constants are described in "MADN In-Use States" (page 5-40).

telCACallPickupMsg

Your tool sends this message when a call pickup activity occurs on a particular call appearance. Your tool should also send this message to the originator of a call if it was picked up at a directory number other than the one dialed. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is unused and should set to 0. The value field contains a constant that indicates the outcome of the call pickup activity. The constants are listed in "Call Pickup States" (page 5-41). The rmtDN, rmtName, rmtSubaddress, and dialType fields specify the directory number whose call was picked up successfully or unsuccessfully. When this message is sent to the call originator, these fields specify the directory number at which the call was picked up.

telCAPagingMsg

Your tool sends this message when (1) an application calls the TELPaging function to access a paging feature for a call appearance, or (2) a user manually initiates a page. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is a paging ID if the telephone system requires one; otherwise, mtype should be 0. The value field is a constant that indicates the outcome of the paging activity. The constants are described in "Paging States" (page 5-39). The rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAIntercomMsg

Your tool sends this message when (1) an application calls the TELIntercom function to access an intercom feature for a call appearance, or (2) a user manually initiates intercom activity. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is an intercom ID if the telephone system requires one; otherwise, mtype should be 0. The value field is a constant that indicates the outcome of the intercom activity. The constants are described in "Intercom States" (page 5-39). The rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAModemToneMsg

Your tool sends this message when a modem tone activity has occurred. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is not used and should be set to 0. The value field is a constant that indicates whether a modem tone has been detected or if it has ceased. The constants are listed in "Modem Tone States" (page 5-38). The rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAFaxToneMsg

Your tool sends this message when a fax tone activity has occurred. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is not used and should be set to 0. The value field is a constant that indicates whether a fax tone has been detected or if it has ceased. The constants are listed in "Fax Tone States" (page 5-38). The rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAIdleMsg

Your tool sends this message when a call appearance reverts to the idle state (telCAIdleState). You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype, value, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0. Note that you should not send an idle message when a new call appearance is created, even though its starting state is the idle state.

telCASuccessiveAlertMsg

Your tool sends this message each time an incoming call rings at the terminal. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype, value, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAUserUserInfoMsg

Your tool sends this message when a remote end sends user-to-user information for a call appearance. (Not all switches support user-to-user information.) You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The rmtDN field contains the user-to-user information. The mtype, value, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAHandOffMsg

Your tool sends this message when an application has registered to receive auto-answered calls (by calling the TELDNSetAutoAnswer function) and an incoming call is auto-answered. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is a Boolean value that indicates whether the call was answered on toll-saver rings. This field should contain true if the call was answered on toll-saver rings. Otherwise, it should contain false. The value field is a Boolean value that indicates whether or not voice has been detected in the incoming call. This field should contain true if voice was detected. Otherwise, it should contain false. The rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCAVoiceDetectedMsg

Your tool sends this message when an application has previously called the TELCAVoiceDetect function to activate voice detection and your tool subsequently detects voice on the line. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype, value, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCASilenceDetectedMsg

Your tool sends this message when an application has previously called the TELCASilenceDetect function to activate silence detection and your tool subsequently detects silence on the line. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The value field should contain the period of time, expressed in seconds, during which silence was detected on the telephone line. The mtype, rmtDN, rmtName, rmtSubaddress, and dialType fields are not used and should be set to 0.

telCADigitsImmMsg

Your tool sends this message when a key is pressed at a remote directory number. You pass information to the Telephone Manager using a call appearance generic message parameter block (page 6-63). The mtype field is a constant that indicates whether or not the key press generated an audible tone. These constants are described in "Audible Digit States" on page 5-32. The value field is the ASCII character for the keypad digit (0-9, #, *) pressed by the remote party. Note that your tool should send both telCADigitsMsg and telCADigitsImmMsg messages for each remote keypress. The rmtDN, rmtName, rmtSubaddress, and dialType fields are unused and should be set to 0.

telCAOtherMsg

Your tool sends this message when it needs to send an application some information about a call appearance that cannot be provided by the other call appearance messages. The values passed in the mtype and value fields are defined by your telephone tool. You should fully describe the supported values in the documentation for your tool.